<!-------- @HEADER
 !
 ! !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
 !
 !  Zoltan Toolkit for Load-balancing, Partitioning, Ordering and Coloring
 !                  Copyright 2012 Sandia Corporation
 !
 ! Under the terms of Contract DE-AC04-94AL85000 with Sandia Corporation,
 ! the U.S. Government retains certain rights in this software.
 !
 ! Redistribution and use in source and binary forms, with or without
 ! modification, are permitted provided that the following conditions are
 ! met:
 !
 ! 1. Redistributions of source code must retain the above copyright
 ! notice, this list of conditions and the following disclaimer.
 !
 ! 2. Redistributions in binary form must reproduce the above copyright
 ! notice, this list of conditions and the following disclaimer in the
 ! documentation and/or other materials provided with the distribution.
 !
 ! 3. Neither the name of the Corporation nor the names of the
 ! contributors may be used to endorse or promote products derived from
 ! this software without specific prior written permission.
 !
 ! THIS SOFTWARE IS PROVIDED BY SANDIA CORPORATION "AS IS" AND ANY
 ! EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 ! IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
 ! PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL SANDIA CORPORATION OR THE
 ! CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
 ! EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
 ! PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
 ! PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
 ! LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
 ! NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
 ! SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 !
 ! Questions? Contact Karen Devine	kddevin@sandia.gov
 !                    Erik Boman	egboman@sandia.gov
 !
 ! !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
 !
 ! @HEADER
-------> 

<HTML>
<HEAD>
   <META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1">
   <META NAME="GENERATOR" CONTENT="Mozilla/4.04 [en] (X11; U; SunOS 4.1.3_U1 sun4m) [Netscape]">
  <meta name="sandia.approval_type" content="formal">
  <meta name="sandia.approved" content="SAND2007-4748W">
  <meta name="author" content="Zoltan PI">


   <TITLE>Zoltan User's Guide:  General Usage Examples</TITLE>
</HEAD>
<BODY BGCOLOR="#FFFFFF">

<div ALIGN=right><b><i><a href="ug.html">Zoltan User's Guide</a>&nbsp; |&nbsp; <a href="ug_examples_lb.html">Next</a>&nbsp; |&nbsp; <a href="ug_examples.html">Previous</a></i></b></div>


<H2>
<A NAME="Initialization Example"></A>General Usage Example</H2>
An example of general Zoltan usage is included below.  This is a C language
example.  Similar C++ examples may be found in the <I>examples</I> directory.
<p>
In this example, <B><A HREF="ug_interface_init.html#Zoltan_Initialize">Zoltan_Initialize</A></B>
is called using the <I>argc</I> and <I>argv</I> arguments to the main program.
Then a pointer to a Zoltan structure is returned by the call to 
<B><A HREF="ug_interface_init.html#Zoltan_Create">Zoltan_Create</A></B>.
In this example, all processors will be used by Zoltan, as
<B>MPI_COMM_WORLD</B> is passed to 
<b><a href="ug_interface_init.html#Zoltan_Create">Zoltan_Create</a></b>
as the communicator.
<p>
Several application query functions are then registered with Zoltan through
calls to <b><a href="ug_interface_init.html#Zoltan_Set_Fn">Zoltan_Set_Fn</a></b>.  
Parameters are set through calls to 
<b><a href="ug_interface_init.html#Zoltan_Set_Param">Zoltan_Set_Param</a></b>.  
The application then performs in computations,
including making calls to Zoltan functions and utilities.  
<p>
Before its execution ends, the application frees memory used by Zoltan by
calling 
<b><a href="ug_interface_init.html#Zoltan_Destroy">Zoltan_Destroy</a></b>.  
<BR>&nbsp;
<CENTER><TABLE BORDER=2 COLS=1 WIDTH="90%" NOSAVE >
<TR NOSAVE>
<TD NOSAVE><A NAME="Init Example Fig"></A><TT>/* Initialize the Zoltan library
*/</TT>&nbsp;
<BR><TT>struct Zoltan_Struct *zz;</TT>&nbsp;
<BR><TT>float version;</TT>&nbsp;
<BR><TT>...</TT>&nbsp;
<BR><TT><A HREF="ug_interface_init.html#Zoltan_Initialize">Zoltan_Initialize</A>(argc,
argv, &amp;version);</TT>&nbsp;&nbsp;
<BR><TT>zz = <A HREF="ug_interface_init.html#Zoltan_Create">Zoltan_Create</A>(MPI_COMM_WORLD);</TT>
<p><tt>/* <i>Register query functions.</i> */</tt>
<br><tt><a href="ug_interface_init.html#Zoltan_Set_Fn">Zoltan_Set_Fn</a>(zz, <a href="ug_query_lb.html#ZOLTAN_NUM_GEOM_FN">ZOLTAN_NUM_GEOM_FN_TYPE</a>, </tt>
<br><tt>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; (void (*)()) user_return_dimension, NULL);</tt>
<br><tt><a href="ug_interface_init.html#Zoltan_Set_Fn">Zoltan_Set_Fn</a>(zz, <a href="ug_query_lb.html#ZOLTAN_GEOM_FN">ZOLTAN_GEOM_FN_TYPE</a>,</tt>
<br><tt>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; (void (*)()) user_return_coords, NULL);</tt>
<br><tt><a href="ug_interface_init.html#Zoltan_Set_Fn">Zoltan_Set_Fn</a>(zz, <a href="ug_query_lb.html#ZOLTAN_NUM_OBJ_FN">ZOLTAN_NUM_OBJ_FN_TYPE</a>,</tt>
<br><tt>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; (void (*)()) user_return_num_node, NULL);</tt>
<br><tt><a href="ug_interface_init.html#Zoltan_Set_Fn">Zoltan_Set_Fn</a>(zz, <a href="ug_query_lb.html#ZOLTAN_OBJ_LIST_FN">ZOLTAN_OBJ_LIST_FN_TYPE</a>,</tt>
<br><tt>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; (void (*)()) user_return_owned_nodes, NULL);</tt>
<p><tt>/* <i>Set some Zoltan parameters.</i> */</tt>
<br><tt><a href="ug_interface_init.html#Zoltan_Set_Param">Zoltan_Set_Param</a>(zz, "debug_level", "4");</tt>
<p><tt>/* <i>Perform application computations, call Zoltan, etc.</i> */</tt>
<br><tt>...</tt>
<p><tt>/* <i>Free Zoltan data structure before ending application.</i> */</tt>
<br><tt><a href="ug_interface_init.html#Zoltan_Destroy">Zoltan_Destroy</a> (&amp;zz);&nbsp;</tt>
</TD>
</TR>

<CAPTION ALIGN=BOTTOM><I>Typical calling sequence for general usage of
the Zoltan library.</I></CAPTION>
</TABLE></CENTER>
&nbsp;

<CENTER><TABLE BORDER=2 COLS=1 WIDTH="90%" NOSAVE >
<TR NOSAVE>
<TD NOSAVE><TT>! Initialize the Zoltan library</TT>&nbsp;
<BR><TT>type(Zoltan_Struct), pointer :: zz</TT>&nbsp;
<BR><TT>real(Zoltan_FLOAT) version</TT>&nbsp;
<BR><TT>integer(Zoltan_INT) ierr</TT>&nbsp;
<BR><TT>...</TT>&nbsp;
<BR><TT>ierr = <A HREF="ug_interface_init.html#Zoltan_Initialize">Zoltan_Initialize</A>(version)
! without argc and argv</TT>&nbsp;&nbsp;
<BR><TT>zz => <A HREF="ug_interface_init.html#Zoltan_Create">Zoltan_Create</A>(MPI_COMM_WORLD)</TT>
<p><tt>! <i>Register load-balancing query functions.</i></tt>
<br><tt>! omit data = C NULL</tt>
<br><tt>ierr = <a href="ug_interface_init.html#Zoltan_Set_Fn">Zoltan_Set_Fn</a>(zz,
<a href="ug_query_lb.html#ZOLTAN_NUM_GEOM_FN">ZOLTAN_NUM_GEOM_FN_TYPE</a>, user_return_dimension)</tt>
<br><tt>ierr = <a href="ug_interface_init.html#Zoltan_Set_Fn">Zoltan_Set_Fn</a>(zz,
<a href="ug_query_lb.html#ZOLTAN_GEOM_FN">ZOLTAN_GEOM_FN_TYPE</a>, user_return_coords)</tt>
<br><tt>ierr = <a href="ug_interface_init.html#Zoltan_Set_Fn">Zoltan_Set_Fn</a>(zz,
<a href="ug_query_lb.html#ZOLTAN_NUM_OBJ_FN">ZOLTAN_NUM_OBJ_FN_TYPE</a>, user_return_num_node)</tt>
<br><tt>ierr = <a href="ug_interface_init.html#Zoltan_Set_Fn">Zoltan_Set_Fn</a>(zz,
<a href="ug_query_lb.html#ZOLTAN_OBJ_LIST_FN">ZOLTAN_OBJ_LIST_FN_TYPE</a>, user_return_owned_nodes)</tt>
<p><tt>! <i>Set some Zoltan parameters.</i></tt>
<br><tt>ierr = <a href="ug_interface_init.html#Zoltan_Set_Param">Zoltan_Set_Param</a>(zz, "debug_level", "4")</tt>
<p><tt>! <i>Perform application computations, call Zoltan, etc.</i></tt>
<br><tt>...</tt>
<p><tt>! <i>Free Zoltan data structure before ending application.</i></tt>
<br><tt>call <a href="ug_interface_init.html#Zoltan_Destroy">Zoltan_Destroy</a>(zz)&nbsp;</tt>


</TD>
</TR>

<CAPTION ALIGN=BOTTOM><I>Fortran version of general usage
example.</I></CAPTION>
</TABLE></CENTER>
&nbsp;

<P>
<HR WIDTH="100%">[<A HREF="ug.html">Table of Contents</A>&nbsp; |&nbsp;
<A HREF="ug_examples_lb.html">Next:&nbsp; Load-Balancing Example</A>&nbsp;
|&nbsp; <A HREF="ug_examples.html">Previous:&nbsp; Examples of Library
Usage</A>&nbsp; |&nbsp; <a href="https://www.sandia.gov/general/privacy-security/index.html">Privacy and Security</a>]
</BODY>
</HTML>
